Memory management¶

The library can use internal memory allocation/deallocation or use provided callbacks for its memory management. The choice is made at compilation time. See the section on customization for details.

If internal management has been selected, the memory callback functions need not be supplied. Even if you do supply them they will not be used. The actual code used is similar to the code discussed in the callback section:

pPtr = calloc (1, iLen);

free (pPtr);

If your compiler does not support these functions, or you wish to monitor the library's use of memory for certain reasons, you can choose to compile the library with external memory management. In this case the memory callback functions MUST be supplied, and should function as if the above code was used.

Initialization¶

The basic initialization of the library is short and swift:

myhandle = mng_initialize (myuserdata, my_alloc,
my_free, MNG_NULL);
if (myhandle == MNG_NULL)
/* process error */;

The first field is an application-only parameter. It is saved in libmng's internal structures and available at all times through the mng_get_userdata() function. This is especially handy in callback functions if your program may be handling multiple files at the same time.

The second and third field supply the library with the memory callback function entry-points. These are described in more detail in the callback section and the previous paragraph.

The fourth and last field may be used to supply the library with the entry-point of a trace callback function. For regular use you will not need this!

The function returns a handle which will be your ticket to MNG-heaven. All other functions rely on this handle. It is the single fixed unique reference-point between your application and the library.

You should call the initialization function for each image you wish to process simultaneously. If you are processing images consecutively, you can reset the internal status of the library with the mng_reset() function. This function will clear all internal state variables, free any stored chunks and/or objects, etc, etc. Your callbacks and other external parameters will be retained.

After you successfully received the handle it is time to set the required callbacks. The sections on reading, displaying & writing indicate which callbacks are required and which are optional. To set the callbacks simply do:

myretcode = mng_setcb_xxxxxx (myhandle, my_xxxxxx);
if (myretcode != MNG_NOERROR)
/* process error */;

Naturally you'd replace the x's with the name of the callback.

Cleanup¶

Once you've gotten hold of that precious mng_handle, you should always, and I mean always, call the cleanup function when you're done. Just do:

mng_cleanup (myhandle);

And you're done. There shouldn't be an ounce of memory spilled after that call.

Note that if you would like to process multiple files consecutively you do not need to do mng_cleanup() / mng_initialize() between each file but simply

myretcode = mng_reset (myhandle);
if (myretcode != MNG_NOERROR)
/* process error */;

will suffice. Saves some time and effort, that.

Error handling¶

From the examples in the previous paragraphs you may have noticed a meticulous scheme for error handling. And yes, that's exactly what it is. Practically each call simply returns an errorcode, indicating success, eg. MNG_NOERROR or failure, anything else but MNG_NEEDMOREDATA and MNG_NEEDTIMERWAIT. These latter two will be discussed in more detail in their respective fields of interest: the reading section and displaying section respectively.

It is the application's responsibility to check the returncode after each call. You can call mng_getlasterror() to receive the details of the last detected error. This even includes a discriptive error-message if you enabled that option during compilation of the library.

Note that after receiving an error it is still possible to call the library, but it's also very likely that any following call will fail. The only functions deemed to work will be mng_reset() and mng_cleanup(). Yes, if you abort your program after an error, you should still call mng_cleanup().

Setup¶

Naturally you must have initialized the library and be the owner of a mng_handle. The following callbacks are essential:

mng_openstream, mng_readdata, mng_closestream

You may optionally define:

mng_errorproc, mng_traceproc
mng_processheader, mng_processtext
mng_processsave, mng_processseek

The reading bit will also fail if you are already creating or displaying a file. Seems a bit obvious, but I thought I'd mention it, just in case.

To suspend or not to suspend¶

There is one choice you need to make before calling the read function. Are you in need of suspension-mode or not?

If you're reading from a disk you most certainly do not need suspension-mode. Even the oldest and slowest of disks will be fast enough for straight reading.

However, if your input comes from a really slow device, such as a dialup-line or the likes, you may opt for suspension-mode. This is done by calling

myretcode = mng_set_suspensionmode (myhandle,
MNG_TRUE);
if (myretcode != MNG_NOERROR)
/* process error */;

Suspension-mode will force the library to use special buffering on the input. This allows your application to receive data of arbitrarily length and return this in the mng_readdata() callback, without disturbing the chunk processing routines of the library.

Suspension-mode does require a little extra care in the main logic of the application. The read function may return with MNG_NEEDMOREDATA when the mng_readdata() callback returns less data then it needs to process the next chunk. This indicates the application to wait for more data to arrive and then resume processing by calling mng_read_resume().

The read HLAPI¶

The actual reading is just plain simple. Since all I/O is done outside the library through the callbacks, the library can focus on its real task. Understanding, checking and labelling the input data!

All you really need to do is this:

myretcode = mng_read (myhandle);
if (myretcode != MNG_NOERROR)
/* process error */;

Of course, if you're on suspension-mode the code is a little more complicated:

myretcode = mng_read (myhandle);

while (myretcode == MNG_NEEDMOREDATA) {
/* wait for input-data to arrive */
myretcode = mng_read_resume (myhandle);
}

if (myretcode != MNG_NOERROR)
/* process error */;

This is rather crude and more sophisticated programming methods may dictate another approach. Whatever method you decide on, it should act as if the above code was in its place.

There is also the mng_readdisplay() function, but this is discussed in the displaying section. It functions pretty much as the mng_read() function, but also immediately starts displaying the image. mng_read_resume() should be replaced by mng_display_resume() in that case!

What happens inside¶

What actually happens inside the library depends on the configuration options set during the compilation of the library.

Basically the library will first read the 8-byte file header, to determine its validity and the type of image it is about to process. Then it will repeatedly read a 4-byte chunk-length and then the remainder of the chunk until it either reaches EOF (indicated by the mng_readdata() callback) or implicitly decides EOF as it processed the logically last chunk of the image.

Applications that require strict conformity and do not allow superfluous data after the ending chunk, will need to perform this check in their mng_closestream() callback.

Each chunk is then checked on CRC, after which it is handed over to the appropriate chunk processing routine. These routines will disect the chunk, check the validity of its contents, check its position with respect to other chunks, etc, etc.

If everything checks out, the chunk is further processed as follows:

If display support has been selected during compilation, certain pre-display initialization will take place.

If chunk-storage support has been selected during compilation, the chunks data may be stored in a special internal structure and held for future reference.

Storing and accessing chunks¶

One of the compilation options activates support for chunk storage. This option may be useful if you want to examine an image. The directive is MNG_STORE_CHUNKS. You must also turn on the MNG_ACCESS_CHUNKS directive.

The actual storage facility can be turned on or off with the mng_set_storechunks() function. If set to MNG_TRUE, chunks will be stored as they are read.

At any point you can then call the mng_iterate_chunks() function to iterate through the current list of chunks. This function requires a callback which is called for each chunk and receives a specific chunk-handle. This chunk-handle can be used to call the appropriate mng_getchunk_xxxx() function, to access the chunks properties.

A typical implementation may look like this:

mng_bool my_iteratechunk (mng_handle hHandle,
mng_handle hChunk,
mng_chunkid iChunkid,
mng_uint32 iChunkseq) {
switch (iChunkid) {
case MNG_UINT_MHDR : { /* process MHDR */;
break; }
case MNG_UINT_FRAM : { /* process FRAM */;
break; }

...etc...

case MNG_UINT_HUH : { /* unknown chunk */;
break; }
default : { /* duh; forgot one */; }
}

return MNG_TRUE; /* keep'm coming */
}

To get to the actual chunk fields of lets say a SHOW chunk you would do:

mng_bool isempty;
mng_uint16 firstid, lastid;
mng_uint8 showmode;

myretcode mng_getchunk_show (hHandle, hChunk,
isempty, firstid,
lastid, showmode);
if (myretcode != MNG_NOERROR)
/* process error */;

Setup¶

Assuming you have initialized the library and are the owner of a mng_handle. The following callbacks are essential:

mng_getcanvasline, mng_refresh
mng_gettickcount, mng_settimer

If you wish to use an application supplied background you must supply:

mng_getbkgdline

If you wish to use the MNG_CANVAS_RGB8_A8 canvas style you must supply:

mng_getalphaline

You may optionally define:

mng_errorproc, mng_traceproc
mng_processheader, mng_processtext
mng_processsave, mng_processseek

Note that the mng_processheader() callback is optional but will be quite significant for proper operation!

Displaying an image will fail if you are creating a file or already displaying one. Yes, you can't display it twice!

A word on canvas styles¶

The canvas style describes how your drawing canvas is made up. You must set this before the library actually starts drawing, so the mng_processheader() callback is a pretty good place for it.

Currently only 8-bit RGB canvas styles are supported, either with or without an alpha channel.

If you like to do alpha composition yourself you can select one of the canvas styles that include an alpha channel. You can even have a separate alpha canvas by selecting the MNG_CANVAS_RGB8_A8 style.

All styles require a compact model. Eg. MNG_CANVAS_BGR8 requires your canvas lines in bgrbgrbgr... storage, where each letter represents an 8-bit value of the corresponding color, and each threesome makes up the values of one(1) pixel.

The library processes a line at a time, so the canvas lines do not actually need to be consecutive in memory.

Alpha composition and application backgrounds¶

All Network Graphics can be partially transparent. This requires special processing if you need to display an image against some background. Note that the MNG header (MHDR chunk) contains a simplicity field indicating whether transparency information in the file is critical or not. This only applies to embedded images, which means the full image-frame of the MNG may still contain fully transparent pixels!

Depending on your needs you can supply a single background color, a background canvas or tell the library to return the alpha-channel and do alpha composition yourself.

This is different from the BACK chunk in a MNG, or the bKGD chunk in an (embedded) PNG or JNG. The BACK chunk indicates an optional or mandatory background color and/or image. The bKGD chunk only indicates an optional background color. These chunks indicate the Authors preferences. They may be absent in which case you need to supply some sort of background yourself.

Composing against a background color¶

This is the easiest method. Call the mng_set_bgcolor() function to set the values of the red, green and blue component of your preferred background color.

Use one of the canvas styles that do not have an alpha-channel, and which matches your output requirements.

Composing against a background canvas¶

This is somewhat more complicated. You will need to set the mng_getbkgdline() callback. This will be called whenever the library needs to compose a partially transparent line.

This canvas must hold the background against which the image should be composed. Its size must match exactly with the image dimensions and thus the drawing canvas!

Use one of the canvas styles that do not have an alpha-channel, and which matches your output requirements. The canvas style of the background canvas may even differ from the drawing canvas. The library's composing will still function properly.

Composing within the application¶

If you have the option in your application to draw a (partially) transparent canvas to the output device, this option is preferred.

Select one of the canvas styles that do have an alpha-channel. The library will now supply the appropriate alpha information, allowing the application to compose the image as it sees fit.

Color information and CMS¶

Network Graphics may, and usually will, contain color-correction information. This information is intended to compensate for the difference in recording and display devices used.

This document does not address the specifics of color-management. See the PNG specification for a more detailed description.

Using little cms by Marti Maria Saguer¶

This is the easiest method, providing you can compile the lcms package. Select the MNG_FULL_CMS directive during compilation, and sit back and relax. The library will take care of all color-correction for you.

Using an OS- or application-supplied CMS¶

If you are so lucky to have access to CMS functionality from within your application, you may instruct the library to leave color-correction to you.

Select the MNG_APP_CMS directive during compilation of the library. You MUST also set the following callbacks:

mng_processgamma, mng_processchroma,
mng_processsrgb, mng_processiccp and
mng_processarow

The last callback is called when the library needs you to correct an arbitrary line of pixels. The other callbacks are called when the corresponding color-information is encountered in the file. You must store this information somewhere for use in the mng_processarow() callback.

Using gamma-only correction¶

This isn't a preferred method, but it's better than no correction at all. Gamma-only correction will at least compensate for gamma-differences between the original recorder and your output device.

Select the MNG_GAMMA_ONLY directive during compilation of the library. Your compiler MUST support fp operations.

No color correction¶

Ouch. This is really bad. This is the least preferred method, but may be necessary if your system cannot use lcms, doesn't have its own CMS, and does not allow fp operations, ruling out the gamma-only option.

Select the MNG_NO_CMS directive during compilation. Images will definitely not be displayed as seen by the Author!!!

Animations and timing¶

Animations require some form of timing support. The library relies on two callbacks for this purpose. The mng_gettickcount() and mng_settimer() callbacks. mng_gettickcount() is used to determine the passing of time in milliseconds since the beginning of the animation. This is also used to compensate during suspension-mode if you are using the mng_readdisplay() function to read & display the file simultaneously.

The callback may return an arbitrary number of milliseconds, but this number must increase proportionaly between calls. Most modern systems will have some tickcount() function which derives its input from an internal clock. The value returned from this function is more than adequate for libmng.

The mng_settimer() callback is called when the library determines a little "pause" is required before rendering another frame of the animation. The pause interval is also expressed in milliseconds. Your application should store this value and return immediately. The library will then make appropriate arrangements to store its internal state and returns to your application with the MNG_NEEDTIMERWAIT code.

At that point you should suspend processing and wait the given interval. Please use your OS features for this. Do not engage some sort of loop. That is real bad programming practice. Most modern systems will have some timing functions. A simple wait() function may suffice, but this may prevent your applications main-task from running, and possibly prevent the actual update of your output device.

The mng_refresh() callback¶

The mng_refresh() callback is called whenever the library has "finished" drawing a new frame onto your canvas, and just before it will call the mng_settimer() callback.

This allows you to perform some actions necessary to "refresh" the canvas onto your output device. Please do NOT suspend processing inside this callback. This must be handled after the mng_settimer() callback!

Displaying while reading¶

This method is preferred if you are reading from a slow input device (such as a dialup-line) and you wish to start displaying something as quickly as possible. This functionality is provided mainly for browser-type applications but may be appropriate for other applications as well.

The method is usually used in unison with the suspension-mode of the read module. A typical implementation would look like this:

/* initiale library and set required callbacks */

/* activate suspension-mode */
myretcode = mng_set_suspensionmode (myhandle,
MNG_TRUE);
if (myretcode != MNG_NOERROR)
/* process error */;

myretcode = mng_readdisplay (myhandle);

while ((myretcode == MNG_NEEDMOREDATA) ||
(myretcode == MNG_NEEDTIMERWAIT)) {
if (myretcode == MNG_NEEDMOREDATA)
/* wait for more input-data */;
else
/* wait for timer interval */;

myretcode = mng_display_resume (myhandle);
}

if (myretcode != MNG_NOERROR)
/* process error */;

More advanced programming methods may require a different approach, but the final result should function as in the code above.

Displaying after reading¶

This method is used to display a file that was previously read. It is primarily meant for viewers with direct file access, such as 1a local harddisk.

Once you have successfully read the file, all you need to do is:

myretcode = mng_display (myhandle);

while (myretcode == MNG_NEEDTIMERWAIT) {
/* wait for timer interval */;
myretcode = mng_display_resume (myhandle);
}

if (myretcode != MNG_NOERROR)
/* process error */;

Again, more advanced programming methods may require a different approach, but the final result should function as in the code above.

Display manipulation¶

Several HLAPI functions are provided to allow a user to manipulate the normal flow of an animation.

- mng_display_freeze (mng_handle hHandle)

This will "freeze" the animation in place.

- mng_display_resume (mng_handle hHandle)

This function can be used to resume a frozen animation, or to force the library to advance the animation to the next frame.

- mng_display_reset (mng_handle hHandle)

This function will "reset" the animation into its pristine state. Calling mng_display() afterwards will re-display the animation from the first frame.

- mng_display_golayer (mng_handle hHandle,
mng_uint32 iLayer)

- mng_display_goframe (mng_handle hHandle,
mng_uint32 iFrame)

- mng_display_gotime (mng_handle hHandle,
mng_uint32 iPlaytime)

These three functions can be used to "jump" to a specific layer, frame or timeslot in the animation. You must "freeze" the animation before using any of these functions.

All above functions may only be called during a timer interval! It is the applications responsibility to cleanup any resources with respect to the timer wait.

Setup¶

As always you must have initialized the library and be the owner of a mng_handle. The following callbacks are essential:

mng_openstream, mng_writedata, mng_closestream

You can optionally define:

mng_errorproc, mng_traceproc

The creation and writing functions will fail if you are in the middle of reading, creating or writing a file.

Creating a new file¶

To start a new file the library must be in its initial state. First you need to tell the library your intentions:

myretcode = mng_create (myhandle);
if (myretcode != MNG_NOERROR)
/* process error */;

After that you start adding the appropriate chunks:

myretcode = mng_put1chunk_mhdr (myhandle, ...);
if (myretcode != MNG_NOERROR)
/* process error */;

And so on, and so forth. Note that the library will automatically signal the logical end of the file by the ending chunk. Also the first chunk will indicate the library the filetype (eg. PNG, JNG or MNG) and force the proper signature when writing the file.

The code above can be simplified, as you can always get the last errorcode by using the mng_getlasterror() function:

if ( (mng_putchunk_xxxx (myhandle, ...)) or
(mng_putchunk_xxxx (myhandle, ...)) or
...etc... )
/* process error */;

Please note that you must have a pretty good understanding of the chunk specification. Unlike the read functions, there are virtually no checks, so it is quite possible to write completely wrong files. It is a good practice to read back your file into the library to verify its integrity.

Once you've got all the chunks added, all you do is:

myretcode mng_write (myhandle);
if (myretcode != MNG_NOERROR)
/* process error */;

And presto. You're done. The real work is of course carried out in your callbacks. Note that this is a single operation as opposed to the read & display functions that may return with MNG_NEEDMOREDATA and/or MNG_NEEDTIMERWAIT. The write function just does the job, and only returns after it's finished or if it encounters some unrecoverable error.

Writing a previously read file¶

If you have already successfully read a file, you can use the library to write it out as a copy or something. You MUST have compiled the library with the MNG_STORE_CHUNKS directive, and you must have done mng_set_storechunks (myhandle, MNG_TRUE).

This doesn't require the MNG_ACCESS_CHUNKS directive, unless you want to fiddle with the chunks as well.

Again all you need to do is:

myretcode mng_write (myhandle);
if (myretcode != MNG_NOERROR)
/* process error */;

Compilation directives¶

not finished yet

Platform dependant modification¶

not finished yet